Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

DBContainers

Adopted By:	DBRecordList

Declared In:	dbkit/containers.h

Protocol Description

When a DBBinder fetches a record from a database, it creates a record object to store the data and stores the record object in a container.  The DBContainers protocol allows an object to be used as just such a container.  See the DBBinder class description for more information on how containers are used.

The DBContainers protocol declares a set of mandatory methods as well as two optional methods, binder:didAcceptObject: and binder:didRejectObject:.  These two are notification methods that are invoked by the DBBinder when objects from the container are used in database-modification operations. 

Note:  The DBBinder class implements DBContainers as a category of List (declared in the header file dbkit/DBBinder.h).  This permits a DBBinder to use a List object as a container.

Method Types

Mandatory methods	- addObject:forBinder:
- count
- empty
- freeObjects
- objectAt:forBinder:
- prepareForBinder:

Optional methods	- binder:didAcceptObject:
- binder:didRejectObject:

Instance Methods

addObject:forBinder:

- addObject:anObject forBinder:(DBBinder *)aBinder

Adds the record object anObject to the container.  If the addition is successful, this returns self, otherwise it returns nil.  This method is invoked automaticallyÐonce per recordÐby the DBBinder that owns the container as it fetches records from the database. 

binder:didAcceptObject:

- binder:(DBBinder *)aBinder didAcceptObject:anObject

This method is automatically invoked by aBinder (the DBBinder that owns the container) after each successful insert, update, or delete operation; anObject is the record object that was operated on.  This is an optional method that a DBContainers-adopting class can implement to create specialized behavior; if the method isn't implemented, then it isn't invoked.  The implementation mustn't change the contents of the container.  The return value is ignored.

binder:didRejectObject:

- binder:(DBBinder *)aBinder didRejectObject:anObject

This method is automatically invoked by aBinder (the DBBinder that owns the container) after each unsuccessful insert, update, or delete operation; anObject is the record object that was operated on.  This is an optional method that a DBContainers-adopting class can implement to create specialized behavior; if the method isn't implemented, then it isn't invoked.  The implementation mustn't change the contents of the container.  The return value is ignored.

count

- (unsigned int)count

Returns the number of objects in the container.

empty

- empty

Removes the container's contents, but doesn't free them. 

freeObjects

- freeObjects

Frees the container's contents. 

objectAt:forBinder:

- objectAt:(unsigned)index forBinder:(DBBinder *)aBinder

Returns the object at the index'th place in the container.  Returns nil if index is out of bounds.

prepareForBinder:

- (unsigned int)prepareForBinder:(DBBinder *)aBinder

Prepares the container for a data operation.  For example, if the container is lazyÐif it compacts, sorts, or otherwise keeps itself up-to-date only on demandÐthen this is the place for it to dust itself off.  Returns the number of objects in the container.